<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<link rel="STYLESHEET" href="lib.css" type='text/css' />
<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
<link rel='start' href='../index.html' title='Python documentation Index' />
<link rel="first" href="lib.html" title='Python library Reference' />
<link rel='contents' href='contents.html' title="Contents" />
<link rel='index' href='genindex.html' title='Index' />
<link rel='last' href='about.html' title='About this document...' />
<link rel='help' href='about.html' title='About this document...' />
<link rel="next" href="node41.html" />
<link rel="prev" href="node39.html" />
<link rel="parent" href="module-string.html" />
<link rel="next" href="node41.html" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name='aesop' content='information' />
<title>4.1.2 Template strings</title>
</head>
<body>
<div class="navigation">
<div id='top-navigation-panel' xml:id='top-navigation-panel'>
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="4.1.1 string constants"
  href="node39.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></a></td>
<td class='online-navigation'><a rel="parent" title="4.1 string  "
  href="module-string.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up one Level' width='32' /></a></td>
<td class='online-navigation'><a rel="next" title="4.1.3 string functions"
  href="node41.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></a></td>
<td align="center" width="100%">Python Library Reference</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></a></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></a></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="node39.html">4.1.1 String constants</a>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="module-string.html">4.1 string  </a>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="node41.html">4.1.3 String functions</a>
</div>
<hr /></div>
</div>
<!--End of Navigation Panel-->

<h2><a name="SECTION006120000000000000000">
4.1.2 Template strings</a>
</h2>

<p>
Templates provide simpler string substitutions as described in <a class="rfc" id='rfcref-98138' xml:id='rfcref-98138'
href="http://www.python.org/peps/pep-0292.html">PEP 292</a>.
Instead of the normal "<tt class="samp">%</tt>"-based substitutions, Templates support
"<tt class="samp">$</tt>"-based substitutions, using the following rules:

<p>

<ul>
<li>"<tt class="samp">$$</tt>" is an escape; it is replaced with a single "<tt class="samp">$</tt>".

<p>
</li>
<li>"<tt class="samp">$identifier</tt>" names a substitution placeholder matching a mapping
       key of "identifier".  By default, "identifier" must spell a Python
       identifier.  The first non-identifier character after the "<tt class="samp">$</tt>"       character terminates this placeholder specification.

<p>
</li>
<li>"<tt class="samp">${identifier}</tt>" is equivalent to "<tt class="samp">$identifier</tt>".  It is
      required when valid identifier characters follow the placeholder but are
      not part of the placeholder, such as "${noun}ification".
</li>
</ul>

<p>
Any other appearance of "<tt class="samp">$</tt>" in the string will result in a
<tt class="exception">ValueError</tt> being raised.

<p>

<span class="versionnote">New in version 2.4.</span>

<p>
The <tt class="module">string</tt> module provides a <tt class="class">Template</tt> class that implements
these rules.  The methods of <tt class="class">Template</tt> are:

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><span class="typelabel">class</span>&nbsp;<tt id='l2h-354' xml:id='l2h-354' class="class">Template</tt></b>(</nobr></td>
  <td><var>template</var>)</td></tr></table></dt>
<dd>
The constructor takes a single argument which is the template string.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-355' xml:id='l2h-355' class="method">substitute</tt></b>(</nobr></td>
  <td><var>mapping</var><big>[</big><var>, **kws</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
Performs the template substitution, returning a new string.  <var>mapping</var> is
any dictionary-like object with keys that match the placeholders in the
template.  Alternatively, you can provide keyword arguments, where the
keywords are the placeholders.  When both <var>mapping</var> and <var>kws</var> are
given and there are duplicates, the placeholders from <var>kws</var> take
precedence.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-356' xml:id='l2h-356' class="method">safe_substitute</tt></b>(</nobr></td>
  <td><var>mapping</var><big>[</big><var>, **kws</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
Like <tt class="method">substitute()</tt>, except that if placeholders are missing from
<var>mapping</var> and <var>kws</var>, instead of raising a <tt class="exception">KeyError</tt>
exception, the original placeholder will appear in the resulting string
intact.  Also, unlike with <tt class="method">substitute()</tt>, any other appearances of the
"<tt class="samp">$</tt>" will simply return "<tt class="samp">$</tt>" instead of raising
<tt class="exception">ValueError</tt>.

<p>
While other exceptions may still occur, this method is called ``safe'' because
substitutions always tries to return a usable string instead of raising an
exception.  In another sense, <tt class="method">safe_substitute()</tt> may be anything other
than safe, since it will silently ignore malformed templates containing
dangling delimiters, unmatched braces, or placeholders that are not valid
Python identifiers.
</dl>

<p>
<tt class="class">Template</tt> instances also provide one public data attribute:

<p>
<dl><dt><b><tt id='l2h-357' xml:id='l2h-357' class="member">template</tt></b></dt>
<dd>
This is the object passed to the constructor's <var>template</var> argument.  In
general, you shouldn't change it, but read-only access is not enforced.
</dl>

<p>
Here is an example of how to use a Template:

<p>
<div class="verbatim"><pre>
&gt;&gt;&gt; from string import Template
&gt;&gt;&gt; s = Template('$who likes $what')
&gt;&gt;&gt; s.substitute(who='tim', what='kung pao')
'tim likes kung pao'
&gt;&gt;&gt; d = dict(who='tim')
&gt;&gt;&gt; Template('Give $who $100').substitute(d)
Traceback (most recent call last):
[...]
ValueError: Invalid placeholder in string: line 1, col 10
&gt;&gt;&gt; Template('$who likes $what').substitute(d)
Traceback (most recent call last):
[...]
KeyError: 'what'
&gt;&gt;&gt; Template('$who likes $what').safe_substitute(d)
'tim likes $what'
</pre></div>

<p>
Advanced usage: you can derive subclasses of <tt class="class">Template</tt> to customize the
placeholder syntax, delimiter character, or the entire regular expression used
to parse template strings.  To do this, you can override these class
attributes:

<p>

<ul>
<li><var>delimiter</var> - This is the literal string describing a placeholder
      introducing delimiter.  The default value "<tt class="samp">$</tt>".  Note that this
      should <em>not</em> be a regular expression, as the implementation will
      call <tt class="method">re.escape()</tt> on this string as needed.
</li>
<li><var>idpattern</var> - This is the regular expression describing the pattern
      for non-braced placeholders (the braces will be added automatically as
      appropriate).  The default value is the regular expression
      "<tt class="samp">[_a-z][_a-z0-9]*</tt>".
</li>
</ul>

<p>
Alternatively, you can provide the entire regular expression pattern by
overriding the class attribute <var>pattern</var>.  If you do this, the value must
be a regular expression object with four named capturing groups.  The
capturing groups correspond to the rules given above, along with the invalid
placeholder rule:

<p>

<ul>
<li><var>escaped</var> - This group matches the escape sequence,
      e.g. "<tt class="samp">$$</tt>", in the default pattern.
</li>
<li><var>named</var> - This group matches the unbraced placeholder name; it
      should not include the delimiter in capturing group.
</li>
<li><var>braced</var> - This group matches the brace enclosed placeholder name;
      it should not include either the delimiter or braces in the capturing
      group.
</li>
<li><var>invalid</var> - This group matches any other delimiter pattern (usually
      a single delimiter), and it should appear last in the regular
      expression.
</li>
</ul>

<p>

<div class="navigation">
<div class='online-navigation'>
<p></p><hr />
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="4.1.1 string constants"
  href="node39.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></a></td>
<td class='online-navigation'><a rel="parent" title="4.1 string  "
  href="module-string.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up one Level' width='32' /></a></td>
<td class='online-navigation'><a rel="next" title="4.1.3 string functions"
  href="node41.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></a></td>
<td align="center" width="100%">Python Library Reference</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></a></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></a></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="node39.html">4.1.1 String constants</a>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="module-string.html">4.1 string  </a>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="node41.html">4.1.3 String functions</a>
</div>
</div>
<hr />
<span class="release-info">Release 2.5.1, documentation updated on 18th April, 2007.</span>
</div>
<!--End of Navigation Panel-->
<address>
See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
</address>
</body>
</html>
